Refund Order

---

POST /api/integrator/order/refund/v2

This POST method is used to refund an order in the Keepz system.

⚠️ Important restriction: An order can only be refunded if:

• Its current status in the Keepz system is SUCCESS, PARTIALLY_REFUNDED, or REFUNDED_FAILED.
• The integrator has refund functionality configured by Keepz.

Refunds are not possible if the order is in any other state.

Request details

When sending request to Keepz, these four parameters must always be included in the body:

identifier

• Unique ID of the integrator in the Keepz system.
• Provided by Keepz during the integration process.

encryptedData

• Contains the actual request payload encrypted using a randomly generated symmetric key and IV (Initialization Vector).

encryptedKeys

• Contains the AES key and IV used to encrypt encryptedData.

aes

• Boolean flag indicating that the request uses AES-based symmetric encryption (needed for backward compatibility with older encryption methods).

For details on the encryption process, see the Encryption Guide documentation.

Parameters

The following parameters form the actual refund payload. They must be included inside the encryptedData parameter, which is encrypted and passed in the request as shown above.

Parameter	Type	Required	Description	Possible values	Note
integratorId	string (UUID v4)	✅	Unique ID of the integrator in the Keepz system. Provided by a Keepz representative.
integratorOrderId	string (UUID v4)	✅	Unique identifier of the order in the integrator’s system.
amount	number / decimal	✅	Refund amount to be returned to the payer.	Positive decimal	Must be ≤ original transaction amount.
refundInitiator	string	❌	Specifies who is initiating the refund.	INTEGRATOR, OPERATOR
refundDetails	array of objects	❌	Optional detailed breakdown of the refund. Each object represents a specific recipient and the portion of the refund allocated to them. Useful for splitting a refund among multiple beneficiaries when the original payment was split.		Details are provided in the dedicated section below.

Complex Types Description

refundDetails

Each object in the array represents one recipient and contains:

Parameter	Type	Required	Description	Possible values	Note
receiverType	string	✅	Type of recipient in the Keepz system.	BRANCH, USER, IBAN	BRANCH – a registered branch in Keepz. USER – a registered user in Keepz. IBAN – an external IBAN account (not registered in Keepz).
receiverIdentifier	string	✅	Unique identifier of the recipient.		For BRANCH and USER, this is a UUID provided by Keepz. For IBAN, this is the IBAN number.
amount	number	✅	Amount to refund to this recipient.	Must be greater than 0.

Response details

✅ Success Response

If the refund request is valid, the API returns an encrypted payload:

{
  "encryptedData": "string",
  "encryptedKeys": "string",
  "aes": true
}

encryptedData

• Contains the actual response payload encrypted using a randomly generated symmetric key and IV (Initialization Vector).

encryptedKeys

• Contains the AES key and IV used to encrypt encryptedData.

aes

• Boolean flag indicating that the request uses AES-based symmetric encryption (needed for backward compatibility with older encryption methods).

For details on the decryption process, see the Encryption Guide documentation.

Inside encryptedData, the following parameters are available after decryption:

Parameter	Type	Possible Values	Description
integratorOrderId	string(UUID v4)		Unique identifier of the order in the integrator’s system.
status	string	REFUND_REQUESTED	Always returned immediately after refund is initiated.

⚠️ The final refund result is processed asynchronously. To check whether the refund was successfully completed ( REFUNDED_BY_INTEGRATOR, PARTIALLY_REFUNDED, REFUNDED_FAILED), use the Get Order Status endpoint.

❌ Error Response

If an error occurs, the response is returned without encryption (plain JSON):

{
  "message": "You can't refund order: Order is already fully refunded",
  "statusCode": 6005,
  "exceptionGroup": 5
}

Parameter	Type	Description
message	string	Error message. Details are provided in the dedicated section below.
statusCode	number	Error status code. Details are provided in the dedicated section below.
exceptionGroup	number	Error group. Details are provided in the dedicated section below.

Details can be found at Error Code Description.